home *** CD-ROM | disk | FTP | other *** search
/ Collection of Tools & Utilities / Collection of Tools and Utilities.iso / batchut / batmen.zip / BATMEN.DOC < prev    next >
Text File  |  1989-06-28  |  19KB  |  416 lines
  1.  
  2.  
  3.                                    BatMenu
  4.  
  5.                              V1.00    28-Jun-1989
  6.     
  7.                  Copyright (C) 1989 by Simple Solutions, Inc.
  8.                              All Rights Reserved
  9.  
  10.                              A Shareware Product
  11.                                      from
  12.  
  13.                             Simple Solutions, Inc.
  14.                                P.O. Box 640189
  15.                                Kenner, LA 70064
  16.                                 (504) 464-5748
  17.  
  18.                                   Written by
  19.                               Mark W. Geisinger
  20.  
  21.                                 CIS 76440,76
  22.                              GEnie M.GEISINGER
  23.                                BIX m.geisinger
  24.  
  25.  
  26. BatMenu is a menu utility intended to be used within DOS batch files.  Well,
  27. that's how it started out anyway.  Explore some of the possibilities here and
  28. you'll see its a bit more than just a "menu utility".
  29.  
  30. BatMenu provides you with a simple interface into a powerful menu control
  31. system which allows you considerable flexibility in displaying windowed text
  32. and prompting your batch file user for a response.  The user of your batch
  33. files is given a sophisticated interface including intelligent circular
  34. scrolling of the highlight bar and bi-directional scrolling of text.
  35.  
  36. BatMenu is a copyrighted work and has been released for distribution as
  37. SHAREWARE.  Please read the file LICENSE.DOC before using BatMenu.
  38.  
  39. Overview
  40. --------
  41.  
  42. BatMenu uses a data file for menu text storage and allows you to store
  43. numerous menus in a single file through the use of "keyword" system. Keywords
  44. are identified in the data file by a "keyword character", or marker,
  45. preceding the keyword as the first character on a line.  The data file size
  46. limits are generous.  You are allowed up to 500 lines of 76 characters each. 
  47.  
  48. Menu selections are returned to your batch file (or other calling program)
  49. via the DOS errorlevel.  There are ten possible values for errorlevel, 0
  50. through 9.  BatMenu reserves 0 (zero) as an error indicator, leaving values 1
  51. through 9 available for your use.
  52.  
  53. Menu Limits
  54. -----------
  55.  
  56. A single menu may, in theory, contain up to 500 lines.  As a practical matter
  57. however, each menu is limited to 9 choices which return a unique value to
  58. your batch file.  The return values correspond directly with the order of the
  59. menu items.  The first menu item sets errorlevel to 1, the ninth menu item
  60. will set errorlevel to 9.
  61.  
  62. If an error occurs, BatMenu returns with errorlevel set to zero.  You'll
  63. find that the error checking in BatMenu is very good for the most likely to
  64. occur errors.  Additionally, an error message is generated if BatMenu aborts
  65. for any reason.
  66.  
  67. Menus with more than nine choices will function properly, except that the
  68. highest return value is 9, so any menu selection by the user past the ninth
  69. item will return with errorlevel set to 9.  This is a limit imposed by using
  70. errorlevel as a method of communication with the batch file, not one imposed
  71. by BatMenu's menu system.
  72.  
  73. Windows with BatMenu
  74. --------------------
  75.  
  76. While BatMenu was not developed as a windowing system, menus and windows here
  77. are closely related and much of the work necessary to display windowed text
  78. has been done in the implementation of the menu system.
  79.  
  80. You can take advantage of this by using BatMenu to display formatted text in
  81. a window. Bi-directional scrolling is allowed. This should come in handy if
  82. you want to place an attractive message on the screen or allow a user of your
  83. batch file to scroll through text or instructions of some kind.  The demo
  84. batch file included here has several examples of just such a usage of
  85. BatMenu.
  86.  
  87. By the way, if you like this aspect of BatMenu let me know.  As I said, much
  88. of the work for a windowing system is place for the menus. Enhancing the
  89. windowing capabilities is certainly possible given the demand for it.
  90.  
  91. Menu/Window Definition
  92. ----------------------
  93.  
  94. Menu definition with BatMenu is simple.  You tell it where to place the menu
  95. and what size it should be.  This is done with four command line parameters
  96. that represent the first-row, first-column, number-rows, and the
  97. number-columns for the menu.  The command line parameters are named as 'fr',
  98. 'fc', 'nr', and 'nc' in the abstract below.
  99.  
  100. Here's the fun part.  This is how you specify to BatMenu where to place the
  101. menu on the screen and what size it should be.  While this is very simple, it
  102. may not be as straightforward as it first appears.  The reason for my
  103. qualification of its simplicity is that you must realize that you are
  104. specifying the menu window borders, not just the size of the text area.
  105.  
  106. BatMenu will attempt to put a leading and trailing space on each line in the
  107. window to separate it from the border. This means the total width of a menu
  108. will be the length of your longest line (limited to 76 char. in the
  109. BATMEN.TXT file) plus 2 characters for the left and right borders, plus two
  110. characters for spacing.  Simply stated, line length + 4 = number-columns.
  111.  
  112.     For instance, if you want a menu that borders your text tightly
  113.     on all sides...
  114.  
  115.        Assuming your menu's first-column is 10
  116.        and your longest menu line is 20 characters
  117.        then, specify the number-columns with the calculation -
  118.  
  119.              first-column + number-columns + 4
  120.                             or
  121.                  10       +       20       + 4 = 34
  122.  
  123.        Thus, 34 would be specified on the command line for the
  124.        'nc' parameter.
  125.  
  126.  
  127. Formatted Text
  128. --------------
  129.  
  130. This is one place where BatMenu doesn't do all the work for you.  That's no
  131. problem though.  You can format the text in a window or menu any way you like
  132. in the data file BATMEN.TXT.  Formatting should be done with spaces, not
  133. embedded tab characters.  Just decide how you want your text to appear in the
  134. window (with consideration of window size, of course), and use your favorite
  135. text editor to edit the BATMEN.TXT file.  Take a look at the BATMEN.TXT
  136. included with BatMenu and you'll see several examples used in the BatDemo
  137. file (I really should go see the movie...).
  138.  
  139. BatMenu will allow the user to scroll forwards or backwards through text that
  140. is larger than the window.  This is bi-directional vertical scrolling.  No
  141. provision is made for horizontal scrolling.  Additionally, long lines will be
  142. truncated when displayed, so check your line length against the window size
  143. you are using to make sure that nothing gets zapped from the end of a line.
  144. This applies to both windows and menus.
  145.  
  146.  
  147. The BATMEN.TXT Data file
  148. ------------------------
  149.  
  150. BatMenu uses a simple ASCII text file for its menu and window data.  The file
  151. must be named BATMEN.TXT.  An example BATMEN.TXT file is included with
  152. BatMenu for use in the demo.  BatMenu uses a very simple "keyword" system to
  153. allow you to store as many menus or windows as you like in the BATMEN.TXT
  154. file.
  155.  
  156. ==== Storing Menu/Window text in the Data file
  157.  
  158. The data stored for a menu or window is simply the ASCII text that will be
  159. displayed in the menu or window.  No translation of characters is done, so
  160. you shouldn't include any control characters or non-printing characters. 
  161. Spacing or formatting should be done only with true spaces, not embedded tab
  162. characters.  Other than that, whatever text you put into the file will be
  163. displayed in the format (spaced) you wrote it.
  164.  
  165. ==== The "keyword" system
  166.  
  167. Different menus or windows are distinguished in the data file using the
  168. "keyword" method mentioned previously.  This is a very simple method that
  169. allows you to store numerous groups of text in one file.  You may think of
  170. the data file being divided into sections by the keywords and you may access
  171. or use any individual section by telling BatMenu which one to use by giving
  172. it the proper keyword.
  173.  
  174. A keyword in the data file must start with an asterisk, '*', and the asterisk
  175. must be the first character on the line containing the keyword.  The
  176. remainder of keyword may be any combination of characters or words that may
  177. otherwise be used